feat: implementation of the stdlib_datetime module by JAi-SATHVIK · Pull Request #1148 · fortran-lang/stdlib

JAi-SATHVIK · 2026-03-17T21:19:03Z

codecov · 2026-03-17T22:17:21Z

Codecov Report

❌ Patch coverage is 81.47590% with 123 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.66%. Comparing base (c016c6d) to head (82a249f).
⚠️ Report is 44 commits behind head on master.

Files with missing lines	Patch %	Lines
src/datetime/stdlib_datetime.f90	75.41%	74 Missing ⚠️
example/datetime/example_datetime_usage.f90	0.00%	46 Missing ⚠️
test/datetime/test_datetime.f90	99.05%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1148      +/-   ##
==========================================
+ Coverage   68.00%   68.66%   +0.66%     
==========================================
  Files         403      407       +4     
  Lines       12850    13599     +749     
  Branches     1383     1534     +151     
==========================================
+ Hits         8738     9338     +600     
- Misses       4112     4261     +149

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

Implements an experimental stdlib_datetime module, along with build integration, documentation, examples, and a new test suite to validate date/time arithmetic, parsing/formatting, and calendar utilities.

Changes:

Added src/datetime/stdlib_datetime.f90 providing datetime_type / timedelta_type, arithmetic/comparison operators, ISO8601 parsing/formatting, and helper utilities.
Integrated the datetime component into the library build and added a datetime test target and example program.
Added a new spec document describing the module API and supported behaviors.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
`src/datetime/stdlib_datetime.f90`	New datetime/timedelta types, operators, ISO parsing/formatting, and calendar utilities.
`src/datetime/CMakeLists.txt`	Adds the datetime library target and links it to core.
`src/CMakeLists.txt`	Adds datetime subdirectory and links it into the top-level stdlib target.
`test/datetime/test_datetime.f90`	New unit tests for leap years, parsing/formatting, arithmetic, comparisons, and rollovers.
`test/datetime/CMakeLists.txt`	Registers datetime as a test target.
`test/CMakeLists.txt`	Adds datetime tests to the test build.
`example/datetime/example_datetime_usage.f90`	New usage example demonstrating common API calls.
`example/datetime/CMakeLists.txt`	Registers datetime example target.
`example/CMakeLists.txt`	Adds datetime examples to the example build.
`doc/specs/stdlib_datetime.md`	New specification page describing the module API and formats.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

JAi-SATHVIK · 2026-03-18T11:13:03Z

Hi @jalvesz, I have a few questions regarding the module implementation. Could you please walk me through them?

Should timestamps without a designator (YYYY-MM-DDTHH:MM:SS) default to UTC (0) or be treated as unspecified?
Should parse_datetime support variable precision (e.g., .5, .50) or only exactly 3 fractional digits?
Should the datetime() constructor validate its arguments (e.g., month=13) or trust the caller to provide valid ranges?

JAi-SATHVIK · 2026-03-22T12:14:20Z

Hi @jalvesz Just checking in to see if there's any additional information I can provide to help with the review process. Happy to make any necessary adjustments!

jvdp1

Thank you @JAi-SATHVIK for this PR. A very complete set of procedures to handle dates an times IMO.

JAi-SATHVIK · 2026-03-24T07:26:17Z

Hi @jvdp1, I've made the requested changes. can you please review the PR?

jalvesz · 2026-03-24T07:46:19Z

Should timestamps without a designator (YYYY-MM-DDTHH:MM:SS) default to UTC (0) or be treated as unspecified?

Having a documented and standard default is a valid option. Can the timestamp designator be retrived from the OS ? that might be the better default.

Should parse_datetime support variable precision (e.g., .5, .50) or only exactly 3 fractional digits?

I think users might want extra precision for seconds and miliseconds, and optional argument with a default ot 3 could be a good way of enabling user desired precision.

Should the datetime() constructor validate its arguments (e.g., month=13) or trust the caller to provide valid ranges?

Would you mind explaining ?

Just wondering, did you take some inspiration from the python datetime module https://docs.python.org/3/library/datetime.html ?

JAi-SATHVIK · 2026-03-24T12:55:08Z

Thanks for the feedback! I've updated the module to use to_string with string concatenation for safer formatting. I also added support for variable fractional second precision in parse_datetime. I've documented that we're defaulting to UTC when the offset is missing as it's the safest cross-platform coordinate and that the datetime() constructor intentionally skips full validation for performance reasons.

Having a documented and standard default is a valid option. Can the timestamp designator be retrived from the OS ? that might be the better default.

Unspecified Timezones: Defaulting to UTC is the safest absolute coordinate, as resolving local offsets for historical/future dates would require a non-intrinsic timezone database.

I think users might want extra precision for seconds and miliseconds, and optional argument with a default ot 3 could be a good way of enabling user desired precision.

Agreed! I've updated parse_datetime to dynamically scan digits (e.g, .5, .50) into milliseconds.

Should the datetime() constructor validate its arguments (e.g., month=13) or trust the caller to provide valid ranges?

parse_datetime is strict for safety, but the datetime() constructor skips bounds checks for speed in tight loops. I’ve added a note to the spec.

Just wondering, did you take some inspiration from the python datetime module https://docs.python.org/3/library/datetime.html ?

Inspiration: The datetime vs timedelta split is heavily inspired by Python’s pattern.

jalvesz

LGTM @JAi-SATHVIK thanks for this nice new functionality!

jvdp1

Thank you @JAi-SATHVIK for this nice addition to stdlib!

cyrilgandon · 2026-04-03T09:11:09Z

Hi, thanks for the great work on this PR, it's really appreciated.

I noticed the mention of potential date_type and time_type sub-types:

"Smaller sub-types if separating only the calendar date from the clock time is deemed necessary."

Do you currently plan to introduce these types as part of a follow-up, or is the intention to keep a single datetime_type for now?

I'm asking because separating date and time can be quite useful in practice, but I understand it also comes with additional API complexity.

Thanks!

JAi-SATHVIK · 2026-04-03T21:16:43Z

Hi @cyrilgandon, thanks for the feedback!

I used a unified datetime_type for now to build a stable foundation with a simpler API. I do plan to add date_type and time_type in a follow up PR once the core logic is tested. Feel free to share any specific use cases you have in mind

cyrilgandon · 2026-04-07T07:08:35Z

Hi, thanks for the clarification!

One concrete use case on my side: I work on STICS, a crop modeling system with a daily time step. We only manipulate calendar dates (year, month, day), and time of day is irrelevant.

In that context, a dedicated date_type would make the code clearer and avoid carrying unused time fields around.

Looking forward to the follow-up PR 🙂

JAi-SATHVIK added 8 commits March 17, 2026 23:51

feat(datetime): implement core datetime and timedelta module

d4ebca8

build add cmakelists

9eeb761

add unit tests for datetime module

8fabb25

build add cmakelists for tests

5eec820

fix missing kp

9b79a06

add example

f7afc17

add example build

92120c8

add functional specification

0d742bd

JAi-SATHVIK marked this pull request as draft March 17, 2026 21:21

JAi-SATHVIK mentioned this pull request Mar 17, 2026

Implement stdlib_datetime - module for Dates, Times, and Time Deltas #1147

Open

jalvesz requested a review from Copilot March 18, 2026 07:15

Copilot started reviewing on behalf of jalvesz March 18, 2026 07:21 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

strictly follow seperators

1e15de6

jvdp1 reviewed Mar 22, 2026

View reviewed changes

add new requirments

18d8ad6

JAi-SATHVIK marked this pull request as ready for review March 22, 2026 17:43

JAi-SATHVIK requested a review from jvdp1 March 22, 2026 18:02

JAi-SATHVIK added 3 commits March 23, 2026 12:05

pure function fix

b4fa181

formatting procedures as pure

f157276

fic pure prefix

d02a595

jalvesz requested changes Mar 24, 2026

View reviewed changes

Comment thread src/datetime/stdlib_datetime.f90 Outdated

update to to_string

05287f7

JAi-SATHVIK requested a review from jalvesz March 25, 2026 11:05

default values

5944659

jalvesz requested changes Mar 26, 2026

View reviewed changes

Comment thread test/datetime/test_datetime.f90 Outdated

check pattern change

82a249f

JAi-SATHVIK requested a review from jalvesz March 27, 2026 18:30

jalvesz approved these changes Mar 30, 2026

View reviewed changes

jvdp1 approved these changes Apr 1, 2026

View reviewed changes

jvdp1 merged commit 923f75f into fortran-lang:master Apr 1, 2026
77 checks passed

Conversation

JAi-SATHVIK commented Mar 17, 2026

Uh oh!

codecov Bot commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JAi-SATHVIK commented Mar 18, 2026

Uh oh!

JAi-SATHVIK commented Mar 22, 2026

Uh oh!

jvdp1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JAi-SATHVIK commented Mar 24, 2026

Uh oh!

Uh oh!

jalvesz commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JAi-SATHVIK commented Mar 24, 2026

Uh oh!

Uh oh!

jalvesz left a comment

Choose a reason for hiding this comment

Uh oh!

jvdp1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cyrilgandon commented Apr 3, 2026

Uh oh!

JAi-SATHVIK commented Apr 3, 2026

Uh oh!

cyrilgandon commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codecov Bot commented Mar 17, 2026 •

edited

Loading

jalvesz commented Mar 24, 2026 •

edited

Loading